<body>

<h2>Overview</h2>
<p>
The game has been implemented as a Java application. It uses an external game
engine Slick which is a 2D game library based on LWJGL3 OpenGL4 binding for
Java.
</p><p>
In the interface we were using a modified version of the Sticky 5 button library.
For the required path finding tasks we used a Java implementation of the A*
algorithm.
</p><p>
Our default planner is SGPlan that can be with some modification in the code with similar PDDL 2.2.
We also have a Planning4J (Java API for connecting various AI planners) however in the current stage we can't fully  use it's strength. When using Planning4J in each stepp we read in our domain file and write it to a temporary one.
</p><p>
As a build automation tool we used Maven.
The program was written in a way to be system independent; however the
majority of the tested planners support only UNIX-like systems, so the use of our
program is limited to this platform family.
</p>

<p>
The main class is called App, this object calls one of the two secondary classes: Visualburglar or LevelGenerator.
</p>

<p>
Visualburglar is the main class of the game. It is implemented as a Slick game library object.
The main game states are MenuState that is the starting point of our game. From there the user can continue to LevelStelectionState to choose a game level and ultimately to GraphicPlayState which is representing the game area.
</p>

<p>The LevelGenerator is the main class of the level creator part of the application that has no graphic environment.</p>

<P>
The program is built of the following program modules that are represented by java packages:
</p>

<p>cz.cuni.mff.abacs.burglar.graphics: the graphic interface.</p>
<p>cz.cuni.mff.abacs.burglar.graphics.multithreading: enables the call of planning and storage objects while the game is running.</p>
<p>cz.cuni.mff.abacs.burglar.logics: contains the world simulation and the level generator main object.</p>
<p>cz.cuni.mff.abacs.burglar.objects: the elements of the game area including the agents and game positions.</p>
<p>cz.cuni.mff.abacs.burglar.planing: the planner interface.</p>
<p>cz.cuni.mff.abacs.burglar.storage: enables loading and saving game levels.</p>

<p>com.aem.sticky: a customized button modul</p>


<h2><Resources directory></h2>

The resources directory contains four subfolders:
<ul>
<li>images: with images used in the gameplay.</li>
<li>sounds: the sound set of the game.</li>
<li>maps: the game levels, to add further levels to the game they must be placed into this directory.</li>
<li>planning: it holds the PDDL domain and problem files, and also the default planning system.</li>
</ul>

<h2>Level files</h2>
<p>
Technically a layout file and a level file looks the same. The only difference is
in the existence of traps. In addition a human developer can easily modify the
output of the level generator to add additional player hints, traps, or any other
objects.
</p><p>
The levels and maps are stored as XML files in the preset map directory; their
exact format is described in the “map.dtd” file found in the map directory.
To work correctly these files have to fulfill the following additional require-
ments:
</p><p>
The world layout must contain at least one room, a single burglar agent,
and a treasure as an aim to collect; every other object is optional. There can’t
be multiple objects with the same unique identifier except for the ones in the
real world and their counterparts in the agents’ beliefs; while these beliefs can’t
contain additional game objects that are non-existent in the true layout.
To be found, the level files must be placed into the map directory on the
resources path.
</p>


<h2>Planning domain</h2>
<p>
The program uses a single unified planning domain file that can be found in the resources directory on the planners/pddl/domain path.</p>


<h2>Usage</h2>

<h3>The game</h3>
<p>
Our program requires a Java executing environment; it can be started with the
following command:
</p>
<p>
run.sh
</p>
<p>
It has four possible command line parameters:
</p>
<ul>
<li>-width NUMBER Sets the screen width in pixels. It can be omitted.</li>
<li>-height <number> Sets the screen height in pixels. It can be omitted.</li>
<li>-rate Displays the current frame rate of the program. It can be omitted.</li>
<li>-replan on knowledge Instructs the agents to replan after gathering new knowl-
edge.</li>
</li>-resources <string> Sets the resource folder path, where the program looks for
the maps, image resources, sounds, and planning tools. It can be omitted,
the default value is “./resources/”.</li>
</ul>


<h3>The generator tool</h3>
<p>
It is a purely console application without graphic output; it can be started with
a following command:
</p><p>
run.sh -generator -m <STRING> -l <STRING> -t <NUMBER>
<p/><p>
It has four possible command line parameters:
<ul>
<li>-generator Informs the program that the user wants to run the level generator,
not the game itself.</li>
<li>-m <string> Sets the path to the input map file where the starting layout can
be found. If no input is defined, tries to receive it from standard input.</li>
<li>-l <string> Sets the path to the output level file where the resulted layout
should be written. If no output is defined, sends the result to standard
output.</li>
<li>-t <number> Sets the required number of pitfalls to be added.</li>
</ul>

<h4>Usage example</h4>
<p>
run.sh -generator -m input_map.xml -l output_level.xml -t 3
</p>
<p>Opens the input map.xml file and attempts to add 3 pitfals to the burglar
agent’s path; finaly puts the resulted map to the output level.xml file.</p>

</body>
